/*
 * $Id: TranslationService.java 7 2013-03-04 05:52:15Z gabakyan@gmail.com $
 * $Author: gabakyan@gmail.com $
 * $Revision: 7 $
 * $Date: 2013-03-04 05:52:15 +0000 (Mon, 04 Mar 2013) $
 *
 * Copyright (c) 2013 Supply Chain Intelligence (SCI), Inc.
 * http://www.scintelligence.com/, Email: info@scintelligence.com
 * All rights reserved.
 *
 * This file is part of Logistics Map.
 *
 * Logistics Map is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, version 3 of the License.
 *
 * Logistics Map is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Logistics Map.  If not, see <http://www.gnu.org/licenses/>.
 */

package com.sci.logisticsmap.support.translator;

/**
 * A service interface for type translation. This is the entry point into the translate system.
 * Call {@link #translate(Object, Object)} to perform a thread-safe type translation using this system.
 */
public interface TranslationService {
    /**
     * Translate the source to target.
     * @param source the source object to translate (required)
     * @param target the target type to translate to (required)
     * @throws TranslationException if a translation exception occurred
     * @throws IllegalArgumentException if source is null
     * @throws IllegalArgumentException if target is null
     */
    <Source, Target> void translate(Source source, Target target);

    /**
     * Translate the source to target.
     * The source and target types provide additional context about the source and target locations where translation will occur, often object fields or property locations.
     * @param source the source object to translate (required)
     * @param target the target type to translate to (required)
     * @param sourceType context about the source type translating from
     * @param targetType context about the target type to translate to (required)
     * @throws TranslationException if a translation exception occurred
     * @throws IllegalArgumentException if source is null
     * @throws IllegalArgumentException if target is null
     */
    <Source, Target> void translate(Source source, Target target, Class<?> sourceType, Class<?> targetType);
}
